/*
 * Copyright 2009 SHOP.COM
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *    http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.shop.opensocial.mediated.services;

import com.shop.opensocial.mediated.request.MediatedRequest;
import com.shop.opensocial.mediated.types.OAuthEntryMediator;
import com.shop.opensocial.mediated.types.SecurityTokenMediator;
import com.shop.opensocial.mediated.types.OAuthConsumerMediator;

/**
 * Independent mediator for corresponding OpenSocial type
 *
 * @author Jordan Zimmerman
 */
public interface OAuthDataStoreMediator
{
	/**
	 * Get the OAuthEntry that corresponds to the oauthToken.
	 *
	 * @param request The request
	 * @param oauthToken a non-null oauthToken
	 * @return a valid OAuthEntry or null if no match
	 */
	public OAuthEntryMediator getEntry(MediatedRequest request, String oauthToken);


	/**
	 * Return the proper security token for a 2 legged oauth request that has been validated
	 * for the given consumerKey. App specific checks like making sure the requested user has the
	 * app installed should take place in this method.
	 *
	 * @param request The request
	 * @param consumerKey A consumer key
	 * @param userId The userId to validate.
	 * @return A valid Security Token
	 */
	public SecurityTokenMediator getSecurityTokenForConsumerRequest(MediatedRequest request, String consumerKey, String userId);

	/**
	 * Lookup consumers.  Generally this corresponds to an opensocial Application
	 * but could be abstracted in other ways.  If you have multiple containers you
	 * may want to include the container as part of the identifier.
	 *
	 * Your consumer object should have the key and secret, a link to your provider
	 * plus you should consider setting properties that correspond to the metadata
	 * in the opensocial app like icon, description, etc.
	 *
	 * @param request The request
	 * @param consumerKey A valid, non-null ConsumerKey
	 * @return the consumer object corresponding to the specified key.
	 */
	public OAuthConsumerMediator getConsumer(MediatedRequest request, String consumerKey);

	/**
	 * Generate a valid requestToken for the given consumerKey.
	 *
	 * @param request The request
	 * @param consumerKey A valid consumer key
	 * @return An OAuthEntry containing a valid request token.
	 */
	public OAuthEntryMediator generateRequestToken(MediatedRequest request, String consumerKey);


	/**
	 * Called when converting a request token to an access token.  This is called
	 * in the final phase of 3-legged OAuth after the user authorizes the app.
	 *
	 * @param request The request
	 * @param entry The Entry to convert
	 * @return a new entry wiht type Type.ACCESS
	 */
	public OAuthEntryMediator convertToAccessToken(MediatedRequest request, OAuthEntryMediator entry);


	/**
	 * Authorize the request token for the given user id.
	 *
	 * @param request The request
	 * @param entry A valid OAuthEntry
	 * @param userId A user id
	 */
	public void authorizeToken(MediatedRequest request, OAuthEntryMediator entry, String userId);
}
